Methods and systems for creating and communicating with computer processes

ABSTRACT

Disclosed are mechanisms for creating and communicating with computer processes. An application programming interface (API) presents services of the system to applications. The API is usable with all processes, local and remote, and is transparent with respect to the location of processes. A process table stores information about processes created using the system. The process table supports centralized process control and peer-to-peer process communication and synchronization. Each process is assigned a Universally Unique Identifier (UUID) that uniquely identifies the process no matter the computing device on which it runs. A parent UUID and a group UUID may be attached to the process and used for enforcing dependencies (e.g., for halting the process and all of its child processes) and for managing arbitrary, user-defined groups, respectively. A global event is associated with each process. When a process receives this event, it performs a controlled shutdown, cleans up, and reports status.

CROSS-REFERENCE TO RELATED APPLICATION(S)

This application is a divisional application of and claims the benefitof U.S. patent application Ser. No. 09/872,257, filed Jun. 1, 2001,content of which is hereby incorporated by reference.

TECHNICAL FIELD

The present invention relates generally to computer operating systems,and, more particularly, to communications mechanisms for computerprocesses.

BACKGROUND OF THE INVENTION

Often, a process running on one computing device may need to create orcommunicate with a process on another device. The use of remote devicesmay simply be a convenience as, for example, when a program requires somany resources that it cannot effectively be run on one device. The workof the program may then be shared among several devices by invokingprocesses on the remote devices to perform pieces of the overall task.The results produced by the remote processes are collected in a central,coordinating process. In other cases, the use of remote devices isinherent in the nature of the work at hand. For example, communicationsprotocols cannot be fully tested on one device. A script for testing aprotocol may be run on a test host device. To perform the test, thescript may start an application on a second device, start a peerapplication on a third device, and start an application on a fourthdevice to monitor the communications between the applications on thesecond and third devices.

Methods exist for a process running on a host computing device to createa process on a remote device. However, these methods provide much lessfunctionality for communicating with the remote process than isavailable for processes running locally. Often, these methods only allowthe host device to start the remote process, receive output from it, andterminate it. The termination is uncontrolled, not giving the remoteprocess a chance to clean up before exiting. Another drawback of thesemethods is the distinction they draw between local and remote processes.This makes it very difficult to debug a program on one device and knowthat it will work correctly when it is running on multiple devices.

Even for purely local processes, current methods of communication are insome ways inadequate. Local processes may be limited in their ability tolog ongoing status information. Termination of local processes may be asuncontrolled as for remote processes.

What is needed is a method that enhances the communications abilities ofall processes and that provides the full functionality of localprocesses to processes on remote computing devices. The method wouldideally hide the distinction between local and remote processes,allowing all processes to be treated in the same manner.

SUMMARY OF THE INVENTION

The above problems and shortcomings, and others, are addressed by thepresent invention, which can be understood by referring to thespecification, drawings, and claims. The present invention providesmechanisms for creating and communicating with computer processes. Anapplication programming interface (API) presents the services of theinvention to applications. The API is usable with all processes, localand remote, and is transparent with respect to the location ofprocesses. The invention also works with processes that do not use theAPI, although some enhanced services are available only to processesusing the API.

A process table stores information about processes created using theinvention. The process table is accessible by all processes, local andremote, and supports centralized process control and peer-to-peerprocess communication and synchronization. Locks are used to synchronizeaccess to the process table.

Each process is assigned a Universally Unique Identifier (UUID) thatuniquely identifies the process no matter the computing device on whichit runs. A parent UUID and a group UUID may be attached to the processand used for enforcing dependencies (e.g., for waiting for or haltingthe process and all of its child processes) and for managing arbitrary,user-defined groups, respectively.

A global event is associated with each process. When a process receivesthis event, it performs a controlled shutdown, cleans up, and reportsits status. Users define other global events and assign meanings tothem. Global events form a generally useful message-passing mechanism.

At frequent intervals, processes and process threads log heartbeatentries in the process table. If a process or thread stops updating thisfield, then other processes can assume that this process or thread brokeinto the debugger. A process may log other information such as thenumber of its threads and the current status of the threads.

BRIEF DESCRIPTION OF THE DRAWINGS

While the appended claims set forth the features of the presentinvention with particularity, the invention, together with its objectsand advantages, may be best understood from the following detaileddescription taken in conjunction with the accompanying drawings ofwhich:

FIG. 1 is a schematic drawing of an exemplary environment in which theinvention may be practiced: multiple computing devices running multipleprocesses and communicating with each other;

FIG. 2 is a block diagram generally illustrating an exemplary computersystem that supports the present invention;

FIGS. 3A and 3B are flow charts showing the steps in creating a processusing the invention; and

FIG. 4 is a schematic diagram of representative process tables.

DETAILED DESCRIPTION OF THE INVENTION

Turning to the drawings, wherein like reference numerals refer to likeelements, the invention is illustrated as being implemented in asuitable computing environment. The following description is based onembodiments of the invention and should not be taken as limiting theinvention with regard to alternative embodiments that are not explicitlydescribed herein.

In the description that follows, the invention is described withreference to acts and symbolic representations of operations that areperformed by one or more computers, unless indicated otherwise. As such,it will be understood that such acts and operations, which are at timesreferred to as being computer-executed, include the manipulation by theprocessing unit of the computer of electrical signals representing datain a structured form. This manipulation transforms the data or maintainsthem at locations in the memory system of the computer, whichreconfigures or otherwise alters the operation of the computer in amanner well understood by those skilled in the art. The data structureswhere data are maintained are physical locations of the memory that haveparticular properties defined by the format of the data. However, whilethe invention is being described in the foregoing context, it is notmeant to be limiting as those of skill in the art will appreciate thatvarious of the acts and operations described hereinafter may also beimplemented in hardware.

Creating and Communicating with Local and Remote Processes

The present invention provides services for creating and communicatingwith computer processes, whether the processes are all running locallyon one computing device or are scattered among several remote devices.Information about processes is gathered into data structures called“process tables.” The process tables are accessible by all processes,local and remote, and support centralized process control andpeer-to-peer process communication and synchronization.

This section provides an overview of the mechanisms and capabilities ofthe invention and includes implementation details only when they areuseful to illustrate the discussion. The following section expands onthis overview by presenting, in great detail, an exemplary embodiment ofthe invention.

FIG. 1 shows an exemplary environment in which the invention may bepracticed. It is a schematic drawing showing multiple computing devices100, 102, and 104 running multiple processes and communicating with eachother via a LAN 106. Computing device 100 is running four processes. Theindentation is intended to show that Process 1 invokes Process 2,Process 2 invokes Process 3, and Process 3 invokes Process 4. Forpurposes of illustration, Process 1 is a command and control interfaceprogram. The user of the computing device 100 invokes other processesthrough this interface. Here, the user invokes Process 2 whichcoordinates and schedules jobs that may comprise several tasks. Process2 invokes Process 3 which is a communications job. To do its work,Process 3 invokes Processes 4, 5, and 6. Processes 4 and 5 communicatewith each other via the LAN 106, Process 4 running on computing device100 and Process 5 running on computing device 102. Process 6 monitorsthe communications between Processes 4 and 5 and runs on computingdevice 104. The choice of a communications job is merely illustrative asthe invention works with all single- or multi-process jobs.

Each computing device runs a service called “spsrv” that coordinatescommunications among the devices. The spsrv service listens for requestscoming in to a device and processes them. These requests includerequests to create a process, requests to provide updated statusinformation, and requests to send information to a process. The spsrvservice also sends out status updates and responses to enquiries. Thisservice generally makes communications details transparent so that anapplication can deal with processes regardless of the device on whichthey are running. Details specific to remote communications arediscussed in the section below entitled “Specific Considerations WhenCommunicating with Remote Processes.”

Each computing device contains a process table that has an entry foreach process running on, or invoked by a process running on, thecomputing device. The process table 108 of computing device 100 containssix entries. The first four entries are for Processes 1 through 4 whichrun on the device. In addition, the process table contains entries forProcess 5 and 6 which do not run locally but were invoked by Process 3which does run locally. Process table 110 on computing device 102contains an entry for Process 5 because that process runs locally, eventhough the process was invoked on another device. Similarly, processtable 112 on computing device 104 contains entries for Process 6,running locally though invoked remotely, and Process 7, running locally.Process 7 illustrates processes running on a computing device that havenothing to do with the job run by the user of computing device 100.Process tables are described in greater detail with reference to FIG. 4.For the moment, note that process tables are populated when a process iscreated and contain information useful for controlling and monitoringthe processes.

The computing devices 100, 102, and 104 of FIG. 1 may be of anyarchitecture. FIG. 2 is a block diagram generally illustrating anexemplary computer system that supports the present invention. Thecomputing device 100 is only one example of a suitable environment andis not intended to suggest any limitation as to the scope of use orfunctionality of the invention. Neither should the computing device 100be interpreted as having any dependency or requirement relating to anyone or combination of components illustrated in FIG. 2. The invention isoperational with numerous other general-purpose or special-purposecomputing environments or configurations. Examples of well-knowncomputing systems, environments, and configurations suitable for usewith the invention include, but are not limited to, personal computers,servers, hand-held or laptop devices, multiprocessor systems,microprocessor-based systems, set-top boxes, programmable consumerelectronics, network PCs, minicomputers, mainframe computers, anddistributed computing environments that include any of the above systemsor devices. In its most basic configuration, computing device 100typically includes at least one processing unit 200 and memory 202. Thememory 202 may be volatile (such as RAM), non-volatile (such as ROM,flash memory, etc.), or some combination of the two. This most basicconfiguration is illustrated in FIG. 2 by the dashed line 204. Thecomputing device may have additional features and functionality. Forexample, computing device 100 may include additional storage (removableand non-removable) including, but not limited to, magnetic and opticaldisks and tape. Such additional storage is illustrated in FIG. 2 byremovable storage 206 and non-removable storage 208. Computer-storagemedia include volatile and non-volatile, removable and non-removable,media implemented in any method or technology for storage of informationsuch as computer-readable instructions, data structures, programmodules, or other data. Memory 202, removable storage 206, andnon-removable storage 208 are all examples of computer-storage media.Computer-storage media include, but are not limited to, RAM, ROM,EEPROM, flash memory, other memory technology, CD-ROM, digital versatiledisks (DVD), other optical storage, magnetic cassettes, magnetic tape,magnetic disk storage, other magnetic storage devices, and any othermedia which can be used to store the desired information and which canaccessed by device 100. Any such computer storage media may be part ofdevice 100. Device 100 may also contain communications connections 210that allow the device to communicate with other devices. Communicationsconnections 210 are examples of communications media. Communicationsmedia typically embody computer-readable instructions, data structures,program modules, or other data in a modulated data signal such as acarrier wave or other transport mechanism and include any informationdelivery media. The term “modulated data signal” means a signal that hasone or more of its characteristics set or changed in such a manner as toencode information in the signal. By way of example, and not limitation,communications media include wired media, such as wired networks(including the LAN 106 of FIG. 1) and direct-wired connections, andwireless media such as acoustic, RF, infrared, and other wireless media.The term computer-readable media as used herein includes both storagemedia and communications media. The computing device 100 may also haveinput devices 212 such as a keyboard, mouse, pen, voice-input device,touch-input device, etc. Output devices 214 such as a display, speakers,printer, etc., may also be included. All these devices are well know inthe art and need not be discussed at length here.

The services of the present invention are presented to applications bymeans of an Application Programming Interface (API). The API can be usedwith all processes, local and remote, and is transparent with respect tothe location of a process. The API returns sensible values if a requestfails because of a network problem and does not falter if remote devicesare unavailable. If a process uses the API, then the process is called a“WINDOWS Test Technologies (WTT)-based process.” The name “WTT” is ofonly historical interest, and the invention is not limited to use in thetesting field or to use with Microsoft's “WINDOWS” operating systems.The invention works with any combination of WTT-based and non-WTT-basedprocesses, although some enhanced services are available only toWTT-based processes. For purposes of this discussion, the servicesprovided by the API are roughly divided into four major categories ofcommunications tasks: creating processes, monitoring processes, waitingfor processes, and sending signals to processes, especially terminationsignals.

Using the API, applications can create new processes and run them eitheron the local computing device or on a remote device. Each process istagged by a Universally Unique Identifier (UUID) that uniquelyidentifies the process no matter the computing device on which itresides. In addition, a parent UUID and a group UUID may be assigned tothe process and used for enforcing dependencies (e.g., for signaling theprocess and all of its child processes) and for managing arbitrary,user-defined groups, respectively. The process table stores informationabout processes created on the computing device, whether the processruns locally on the device or runs remotely. The process table iscreated as a memory-mapped file and is visible to all processes on thedevice. A global event is associated with each process created via theAPI and is used for process control and signaling.

FIGS. 3A and 3B illustrate the steps taken when a process is created bymeans of calls to the API. In step 300 of FIG. 3A, the API is called tocreate a process. The call is made by a parent application running onthe “source” computing device. Steps 302, 304, and 306 set upinformation associated with the new process and record that informationin the process table on the source device. If desired, a group UUID,parent UUID, or other information can be added to the process table (notshown). Step 308 asks whether the new process will run on the sourcedevice or on a remote device. If the new process is to run on the sourcedevice, as, for example, when Process 3 in FIG. 1 invokes Process 4, thenew process is started in step 310. Otherwise, step 314 sends pertinentinformation about the new process to the spsrv service running on theremote device, called the “target” device, on which the process willrun. This is the case when Process 3 in FIG. 1 invokes Process 6. Theinformation necessary for invoking Process 6 is sent from the sourcedevice 100 to the target device 104. FIG. 3B illustrates what happens onthe target device when it receives a request from the source device torun a process. After receiving the request in step 318, the targetdevice creates an entry for the process in its process table, step 320,and runs the process, step 322. Note that in the case where the sourceand target devices are distinct, the process table on each device has anentry for the process. Process 6 shows up both in the process table 108on the source device 100 and in the process table 112 on the targetdevice 104. This is an implementation detail and is not necessary forthe invention, but it helps when monitoring and controlling remoteprocesses, as discussed further below.

FIG. 4 is a schematic diagram of representative process tables. Thetables are populated to reflect the situation in FIG. 1. The first fieldshown, the UUID assigned to each process, is a useful key into theprocess tables. Next, the Process ID is assigned by the operating systemwhen the process is created. Because the operating system may notunderstand the UUID, the Process ID is available when operating systemcalls need to be made in relation to a process. The Parent UUID andGroup UUID are optional fields and are discussed above. Creation Timemarks the moment when the process began running. Heartbeat Time storesthe last time that a WTT-based process posted a heartbeat update. Usesof the heartbeat timer are discussed further below. The Source Deviceand Target Device fields identify the computing device where the processwas invoked and where it runs, respectively. For local processes such asProcess 3, these fields contain the same value. The fields also containthe same value in the process table on the target machine, as shown bythe Process 6 entry in Process Table 112. The specific semantics ofthese two fields are unimportant, as long as the values uniquelyidentify the devices. Some possible values are the name of the computingdevice and its IP address. The final field shown, Process Type, is aflag showing whether the process is aware of this API. A Process Tablemay contain other fields, not shown, and some of these other fields arediscussed below. The fields illustrated in FIG. 4 are, arguably, thebasic fields used by the API.

Because a process table is accessible to all processes on the computingdevice, mechanisms exist for coordinating access to the table. Onemechanism involves software locks, both for the entire table and foreach individual row. For example, a process updating its heartbeat timecan lock access to its row while it writes the current time into theHeartbeat Time field. When a process is created or deleted, the entireprocess table is locked so that a row can be added or deleted withoutinterference.

At frequent intervals, for each process, a monitor thread logs heartbeatentries in the Heartbeat Time field in the local process table. Eachthread in a process updates a local heartbeat and the monitor threadkeeps track of these local heartbeats, updating the heartbeat field inthe local process table if all the threads are updating their localheartbeats. If any thread deadlocks and stops updating its localheartbeat, the monitor thread detects this, logs the fact, and eitherbreaks into the debugger or marks the process as requiring assistance.When an application wants to monitor the heartbeat of a process, theapplication begins by looking up the entry for the process in theprocess table on the computing device on which the application isrunning. The application reads the Target Device field to see where theprocess is running. Then, if the target device is the local device, theapplication reads the Heartbeat Time field in the local process table.Otherwise, the target device is distinct from the local device and theapplication sends a request to the spsrv service running on the targetdevice asking it to send the value of the Heartbeat Time of the process.For example, if Process 3 in FIG. 1 wants to know whether Process 6 isstill running normally, that is to say, is still logging heartbeats,Process 3 would consult Process Table 108 on its local computing device100. Reading the entry for Process 6, Process 3 discovers that Process 6is running remotely, on computing device 104. (See FIG. 4.) Process 3formulates a request and sends it to the computing device 104. Thatdevice reads its process table 112 and reports to Process 3 that theHeartbeat Time field of Process 6 currently reads “14:24:56”. Process 3compares that heartbeat time (adjusted, if necessary, for time zonedifferences) to its local clock and decides whether Process 6 is runningor has broken into the debugger.

In addition to its heartbeat, a process may log other informationincluding the number of its threads, the current status of the threads,console output, log file output, etc. An application wishing to monitorthis output can use the same techniques described above with respect toheartbeats. The application can also obtain ongoing status informationby requesting that a copy of new information written by the process besent to the application as it is written. Using parent and group UUIDs,an application can monitor all of the processes in a dependency list orin a user-defined process group.

A process may wait for other processes to achieve a specified status,for example, to complete their initialization or to terminate. The APIprovides a function that waits until the processes achieve the status oruntil a timeout period elapses. The function checks the heartbeat of allWTT-based processes and, if a process is not logging heartbeats, thenthe process may be assumed to have broken into the debugger. Using theprocesses in FIG. 1 as an example, assume that Process 3 calls the APIfunction to wait for Processes 4, 5, and 6 to complete theirinitialization. Because Processes 5 and 6 run on remote computingdevices, the API function sends a wait request to those remote devices.Each device waits on the processes local to it and then reports theresults to Process 3. For each process in the wait list, the returnedstatus may be Completed Initialization, Still Initializing, or HeartbeatStopped. Using UUIDs in the same manner as in process monitoring, aprocess can wait for all of the processes in a dependency list or in auser-defined process group. Note that because non-WTT-based processes donot update their Heartbeat Time field, it cannot be assumed that theseprocesses broke into the debugger.

When a job is divided into discrete processes, the processes often needto communicate among themselves to coordinate the tasks they perform.The API provides a generally useful signaling mechanism for this purposein the form of Global Events. As an example, one particular event is theControlled Shutdown. When a WTT-based process receives this event, itreleases the resources it is using, reports its status, and performs acontrolled shutdown. Users may define other Global Events and assignmeanings to them. When a process receives an event, it responds in afashion appropriate to the event's meaning. However, if a processreceives an event it does not understand, it may terminate in anuncontrolled fashion. A process may use parent and group UUIDs to sendan event to groups of processes.

An Exemplary Application Programming Interface

The services provided by the invention as described in the previoussection are presented again in this section but with more attention paidto the details of an exemplary API. In its specific details, thisembodiment is oriented towards use with Microsoft's “WINDOWS” operatingsystem, but the principles are applicable to other environments. Thissection begins by describing the fundamental data structures used inthis embodiment.

Note that UUIDs are sometimes called GUIDs (Globally UniqueIdentifiers).

The variable types TCHAR and Tstring are used in the definitions belowto provide source code compatibility between Unicode and non-Unicodemachines. If the parameter _UNICODE is defined during the build, thenTCHAR is defined to be the Unicode's basic wide character type,“wchar_t,” otherwise it becomes the standard ASCII 8-bit signed “char.”Similarly, Tstring is a string of TCHARs and becomes either the Unicodewide string, “wstring,” or ASCII “string.”

1 WTTPROCESSPARAM

Describes the input parameters to the WTTCreateProcess call. // From thewinbase.h file. #define MAX_COMPUTERNAME_LENGTH 31 // Type of processes:WTT-based or not. #define WTT_PROC_TYPE_NONWTT_BASED  1 #defineWTT_PROC_TYPE_WTT_BASED  2 // System processes and other non-WTT-basedprocesses launched outside the // scope of the API. #defineWTT_PROC_TYPE_SYSTEM_BASED  3 typedef struct_WTTPROCESSPARAM { // Sizeofthis structure (including this field). User needs to input a value of //sizeof(WTTPROCESSPARAM) for this. IN DWORD dwStructSizeOf; // Flags.Reserved: must be zero (MBZ). IN DWORD dwFlags; // Flags used inWTTCreateProcess. Only CREATE_NEW_CONSOLE, // CREATE_NEW_PROCESS, andDETACHED_PROCESS are currently // supported. IN DWORDdwCreateProcessFlags; // Is this a WTT-based process? IN DWORDdwProcessType; // The username and password to use when running theprocess. The password // is unencoded text but is encrypted beforesending to the target device. IN TCHAR *szUserName; IN TCHAR*szPassword; // The command line to execute when starting the process.IN TCHAR *szCommandLine; // NULL or a debugger string such as “ntsd -g”.IN TCHAR *szDebugger; // NULL or the UNC-style (e.g.,\\machine\share\path . . .) name of a generated // log file. IN TCHAR*szLogFile; // The directory where the process is created. Can be NULL,which means use // the current directory for launching the process. INTCHAR *szCurrentDirectory; // If the process was invoked remotely, thenget the GUID from the caller. // From an external caller's perspective,this is not provided as an input. UUID Guid; // This optionallyidentifies a group with which the process is associated. UUID GroupGuid;// The GUID of the parent of this process. There may be a chain ofparent- // child processes. UUID ParentGuid; // The identity of thetarget computing device, for example, its name or IP // address. INTCHAR szTargetMachine[MAX_COMPUTERNAME_LENGTH + 1]; } WTTPROCESSPARAM,*PWTTPROCESSPARAM;

By associating a group GUID with a set of processes, processes cancommunicate with all the processes in the set. This is similar to a“process group” in Windows NT or Unix.

2 WTTPROCLISTINFO

Defines information relating to a process. WTTGetProcessListInfo returnsthis information. A pointer to this structure is passed as an inputparameter to WTTOpenProcess. An application receives a handle to aprocess by calling WTTOpenProcess and can use that handle to monitor theprocess, even if the process was not created by the application. typedefstruct_WTTPROCLISTINFO { // The GUID, Process ID, and type of theprocess. The process type can be: // WTT_PROC_TYPE_NON_WTT_BASED(defined to be 1); // WTT_PROC_TYPE_WTT_BASED (2); or //WTT_PROC_TYPE_SYSTEM_BASED (4). UUID Guid; DWORD dwPid; DWORDdwProcType; // These variables are meaningful only if the process isWTT-based and is // logging heartbeats. For non-WTT-based processes,dwHBTime is zero and // ulLastHBUpdateTime is the time the process wascreated. DWORD dwHBTime; ULARGE_INTEGER ulLastHBUpdateTime; // Thenumber of seconds since the process was created (reported as zero for //non-WTT-based processes). DWORD dwElapsedSeconds; // This is the statusof the process. Its possible values are given below in the // sectiondescribing WTTGetProcessInfo. For non-WTT-based processes, the //reported status is WTTHANDLE_PROCSTATUS_UNDEFINED. DWORD dwProcStatus;// The module name (not fully qualified with path). TCHARszModuleName[256]; } WTTPROCLISTINFO, *PWTTPROCLISTINFO;

Holds information about a thread including the Thread Identifier and alist of comments. Comments may be pushed onto the stack, and the mostrecent comment may be popped off the stack and examined. typedef struct_WTTTHREADINFO { DWORD dwThreadId; // The Standard Template Library(STL) contains type-parameterized classes. // slThreadCommentStack is anSTL stack of STL strings. stack <string> slThreadCommentStack; }WTTTHREADINFO, *PWTTTHREADINFO; WTTPROCESSINFO Holds detailed processinformation. typedef class _WTTPROCESSINFO { // All members are public(can use a ctor and a dtor). public: DWORD dwProcType; // Status of theprocess (initialized, debug break, terminated, etc.). This is // thesame as in the WTTPROCLISTINFO structure. That one is there for //convenience only. DWORD dwProcStatus; UUID Guid; DWORD dwProcPid; DWORDdwProcExitCode; // Time elapsed since the creation of the process.ULARGE_INTEGER ulElapsedTime; TCHAR *pszModuleName; TCHAR*pszCommandLine; TCHAR *pszTargetMachine; // Singly-linked list ofthread information (used to store elements of type // WTTTHREADINFO).list <PWTTTHREADINFO> slThreadList; // List of log files associated withthe process. list <string> slLogList; // List of variations covered.list <string> slVarnList; public: _WTTPROCESSINFO( ). { pszModuleName =new TCHAR[MAX_PATH]; pszCommandLine = new TCHAR[MAX_CMD_LINE];pszTargetMachine = new TCHAR[MAX_COMPUTERNAME_LENGTH + 1]; } }WTTPROCESSINFO, *PWTTPROCESSINFO; WTTP_LOG_INFO typedef struct_(——)WTTP_LOG_INFO { TCHAR szLogFileName[128];  // UNC path of log file.} WTTP_LOG_INFO, *PWTTP_LOG_INFO6 HWTTPROCESS

This structure is opaque to the user and is used as a handle for futureoperations. This process-specific handle may be replaced by WTTHANDLE.

7 WTTHANDLE

This data structure is opaque to the user and is used as a handle forfuture operations. This handle is capable of handling objects no mattertheir type—whether processes, events, mutexes, etc. For “WINDOWS”implementations, this handle is similar to the handles used by Win32processes. typedef struct _WTT_HANDLE { // The exit status of theprocess as would be returned by a local call to the // Win32 functionGetExitCodeProcess( ). DWORD dwStatus; // The Process Identifier of acreated child. DWORD dwProcID; // Was the process successfully created?If not, then this is set to // ERROR_SERVICE_NOT_ACTIVE. DWORDdwProcCreationStatus; // This points to information such as theheartbeat timer, etc. This field is // opaque and only makes sense onthe device on which the process is created. PWTT_SHAREDINFO pSharedInfo;// The current status of the process. DWORD dwProcStatus; // Store thefollowing data in the process handle. While marshaling the //parameters, the offsets are clearly defined and the strings are puttowards the // end of the buffer. // If the call comes from a remotedevice, then get the GUID from the caller. UUID Guid; TCHAR*szCommandLine; // The following two parameters are supplied in case theprocess needs to be // launched by a specified user. TCHAR *szUserName;TCHAR *szPasswd; // Both for storage in the local process table and forredirection. TCHAR *szTargetMachineName; TCHAR *szModule; // The objecttype can be WTT_PROC_OBJECT, WTT_EVENT_OBJECT, // etc. DWORDdwObjectType; PHANDLE hObjectHandle; } WTT_HANDLE, *WTTHANDLE;

Having presented the data structures used in this implementation, thefollowing describes the function calls provided by the API.

8 WTTCreateProcess

Create a process, whether WTT-based or not. The user's input parametersare passed in as part of the WTTPROCESSPARAM structure. The returnedstructure pointer (pHWTTProcess) is opaque and is used in future calls.If UserName and Password are specified as part of the input structure,then the process is created with the logon credentials of the specifieduser.

The call is basically asynchronous in nature and returns as soon aspossible after the process is successfully created or with a meaningfulerror value explaining why the process creation failed. DWORDWTTCreateProcess ( IN OUT PWTTPROCESSPARAM pWTTProcessParam, OUTWTTHANDLE *pHWTTProcess );Parameters:pWTTProcessParam

Points to a structure of type WTTPROCESSPARAM, which contains the inputparameters. Some of the fields in this structure are appropriatelyupdated to store output values. For example, if the passed in GUID is“NIL” (see Note on UUIDs below), then the newly created GUID is storedwhen the function returns.

The following flags are supported in the WTTPROCESSPARAM structure'sdwCreateProcessFlags field: CREATE_NEW_CONSOLE, CREATE_NEW_PROCESS, andDETACHED_PROCESS.

pHWTTProcess

An opaque pointer used in future calls to the API for accessinginformation about the process.

Return Values:

ERROR_SUCCESS if the process is successfully created, else Win32 error.In the latter case, the returned handle is NOT valid.

Implementation Notes:

This function assigns a GUID to the process that uniquely identifies theprocess no matter the device on which it runs. Then the function locksaccess to the process table and finds an empty slot in the table.Assigning the slot to the new process, this function stores in the slotthe initial data for the process including its GUID, Parent GUID, GroupGUID, etc. The parent of the process updates the heartbeat field andwrites a zero value into the HB field. This makes it possible for theWTTWaitForMultipleObjects function to detect a DEBUG_BREAK that occursbefore the creation of the Global Event.

If the process is to run on a remote device, then the parameters of thecall are marshaled over the network and sent to the remote (target)device. The process is then created locally on the target device.

Once the new process starts, its status in the process table (thedwProcStatus field) is automatically updated.

9 WTTSignalProcesses

Send a signal to the processes in a set. The set may include bothWTT-based and non-WTT-based processes. The global event handle is setfor each process. One currently defined signal is “terminate theprocess.” On receipt of that signal, a process cleans up after itselfand performs a controlled stop. Sending a terminate signal is similar tosending a “kill” signal. DWORD WTTSignalProcesses ( IN DWORD nCount, INWTTHANDLE *phWTTProcess, IN DWORD dwFlags );Parameters:nCount

The number of processes in the phWTTProcess array.

phWTTProcess

The set of processes to signal. This is an array of WTTHANDLEs forWTTProcesses as returned by the WTTCreateProcess and WTTOpenProcessfunctions.

dwFlags

The type of signal to send:

-   -   WTT_SIGNAL_PROCESS

Attempt a controlled stop by signaling the event associated with theprocess. It is the responsibility of non-WTT-based processes to checkthe global event.

-   -   WTT_TERMINATE_PROCESS

Force-terminate the process. This cannot be combined withWTT_SIGNAL_PROCESS.

-   -   WTT_TERMINATE_ALL_CHILDREN

This terminates all processes in a process tree. For every process inthe process tree, internal process APIs are recursively used toterminate the children. The process table is searched to find all thedescendents so that they can be signaled.

Return Values:

ERROR_SUCCESS if the signal is successfully sent, else Win32 error.

Implementation Notes:

For non-WTT-based processes, the standard global event handle issignaled. If a non-WTT-based process does not clean up within anacceptable period of time after being sent a WTT_SIGNAL_PROCESS signal,then the calling process can send a WTT_TERMINATE_PROCESS signal.

10 WTTWaitForMultipleObjects

Wait for processes in a set to achieve a specified status, but stopwaiting if a timeout period expires. The function checks the heartbeatsof all WTT-based processes, and if a process is not logging heartbeats,then it is assumed to have broken into the debugger. This function isoften used to wait for processes to terminate. In that case, thedifferent possible scenarios on returning from this function are asfollows:

-   -   all processes stopped successfully;    -   some processes stopped successfully, and some processes broke        into the debugger; and    -   some processes stopped successfully, some broke into the        debugger, and some did neither but are still logging heartbeats.        In the last case, the function timed out before all the        processes were finished so the function returns the value        WAIT_TIMEOUT.

A debug break cannot be declared for a non-WTT-based process becausethis type of process does not log heartbeats. DWORDWTTWaitForMultipleObjects ( IN DWORD nCount, IN WTTHANDLE *phWTTProcess,IN BOOL fWaitAll, IN DWORD dwTimeoutInSeconds, IN DWORDdwDebugTimeoutInSeconds, IN DWORD dwWaitType, OUT DWORD*pdwSummaryStatus, OUT DWORD *pdwSummaryIndex )Parameters:nCount

The number of processes in the phWTTProcess array.

phWTTProcess

The set of processes stored as an array of WTTHANDLEs.

fWaitAll

TRUE means wait for all processes in the set. FALSE means wait for thefirst process to achieve the specified status.

dwTimeoutInSeconds

The function timeout period. The function waits no longer than thisbefore returning. If a process does not achieve the specified status(e.g., terminated) during this period of time, its status is returned asWAIT_TIMEOUT.

dwDebugTimeoutInSeconds

If a process has not logged a heartbeat during this period, then theprocess is declared to have broken into the debugger. The value of thisparameter may be smaller than the value of dwTimeoutInSeconds. A valueof INFINITE is also possible which effectively ignores heartbeats.

If fWaitAll is TRUE, then the value of this parameter should be themaximum of the debug timeout values of all the processes in themonitored set.

dwWaitType

The type of status to wait for. These values cannot be combined. Manymore statuses are possible; the following are currently implemented:

-   -   WTT_PROCESS_INITIALIZE

Wait for the processes to complete their initialization.

-   -   WTT_PROCESS_TERMINATE

Wait for the processes to finish.

pdwSummaryStatus

The address to receive the first failure status of the array (or NULL ifthis information is not desired). This field is meaningful only if thereturn value is ERROR_SUCCESS and if fWaitAll is FALSE.

pdwSummaryIndex

The address to receive the index corresponding to the summary status (orNULL if this information is not desired).

Return Values:

ERROR_SUCCESS if all the processes successfully achieve the specifiedstatus.

WAIT_TIMEOUT if the timeout expires before all the processes achieve thespecified status. In this case, *pdwSummaryIndex and *pdwSummaryStatusare undefined.

WTT_ERROR_DEBUG_BREAK if a process breaks into the debugger.*pdwSummaryStatus contains WTT_ERROR_DEBUG_BREAK and the index of thatprocess in the phWTTProcess array is returned in *pdwSummaryIndex. Therecould be several processes in such a state in which case pdwSummaryIndexpoints to the first one.

Win32 if the function call fails.

Implementation Notes:

When processes in the set run on a distributed set of computing devices,there may be one thread per process (or one per computing device) whichthe overall thread monitors.

For non-WTT-based processes, dwLastHBUpdateTime is the time the processwas created and is not updated. No debug break can be declared for theseprocesses.

11 WTTGetProcessInfo

Query the status of a process that was launched by the WTTCreateProcessfunction. After reviewing the information returned, WTTFreeProcessInfois called to release the memory allocated by this function. DWORDWTTGetProcessInfo ( IN WTTHANDLE   phWTTProcess, OUT PWTTPROCESSINFO*ppWTTProcessinfo );Parameters:phWTTProcess

Process information is stored in a WTTHANDLE structure. The handle couldhave been obtained either by a call to WTTCreateProcess or by a call toWTTOpenProcess (after a call to WTTGetProcessListInfo).

Additionally, this could have a value of NULL. In that case, theinformation returned pertains to the process that called this function.This is useful when a non-WTT-based process wishes to get GUIDinformation about itself, which it can then use to open a handle to theGlobal Event.

ppWTTProcessinfo

This stores information about the process being queried. The informationincludes the threads present, the stack of thread comments for eachthread, a list of log files that this process monitors, and a list ofvariations completed by the process.

Return Values:

ERROR_SUCCESS if the request is successfully processed, else Win32error.

Implementation Notes:

For WTT-based processes, the following information is returned:

-   -   a list of the threads present in the process;    -   a stack of comments stored on a per-process basis;    -   a list of log files that are directly created by the process;    -   a list of variations covered by the process;    -   the module name;    -   the type of the process (WTT_PROC_TYPE_WTT_BASED); and    -   the current state of the process.

The data returned are stored in the form of simple link lists or stacks.Small routines are provided to return the size, traverse, and list thecontents of the lists or stacks.

For non-WTT-based process, a list of thread identifiers, the modulename, the type of the process, and the current state of the process arereturned. The current state of the process may not be very accuratebecause non-WTT-based processes do not log heartbeats.

The process statuses are:

-   -   WTTHANDLE_PROCSTATUS_UNDEFINED    -   WTTHANDLE_PROCSTATUS_INITIALIZED    -   WTTHANDLE_PROCSTATUS_RUNNING    -   WTTHANDLE_PROCSTATUS_GE_CREATED (The Global Event is ready for        signaling.)    -   WTTHANDLE_PROCSTATUS_TERMINATED    -   WTTHANDLE_PROCSTATUS_DEBUG_BREAK    -   WTTHANDLE_PROCSTATUS_HANDLE_CLOSED        The macro GET_PROC_STATUS(pWTTProcessinfo->dwProcStatus) returns        a string corresponding to the process status.        12 WTTFreeProcessInfo

Release the memory allocated within the WTTPROCESSINFO structure duringa WTTGetProcessInfo function call.

DWORD WTTFreeProcessInfo(IN PWTTPROCESSINFO *ppWTTProcessinfo);

Parameter:

ppWTTProcessinfo

Pointer to a pointer to a structure containing information about aprocess returned by a call to WTTGetProcessInfo.

Return Values:

ERROR_SUCCESS if the allocated memory is successfully released, elseWin32 error. The pointer to the WTTPROCESSINFO structure is not definedafter a call to this function.

13 WTTGetProcessListInfo

Get the process list from the target machine's process table. Theinformation returned varies depending upon the values specified indwFlags. Memory allocation is done within the function call itself.WTTFreeProcessListInfo is called to release the memory after reviewingthe information returned. DWORD WTTGetProcessListInfo ( IN LPCTSTRpszMachine, BOOL bResolveRemote, IN DWORD dwFlags, OUT DWORD *pdwCount,OUT PWTTPROCLISTINFO *ppWTTProcessListInfo );Parameters:pszMachine

The name of the computing device from which to retrieve the processtable information.

bResolveRemote

TRUE means remote entries should be resolved. In that case, extraheartbeat-related information is retrieved for processes initiated byWTTCreateProcess on the computing device specified by pszMachine. Aquery is made to that remote device.

dwFlags

Include_wtt_based_procs

Include all WTT-based processes created by WTTCreateProcess orotherwise.

Include_non_wtt_based_procs

Include non-WTT-based processes created by WTTCreateProcess.

Include_system_procs

GUID is displayed as NULL for these. WTTOpenProcess cannot be called forprocesses of this type.

pdwCount

Pointer to the number of elements in the ppWTTProcessListInfo array.

ppWTTProcessListInfo

An array of output information for the processes.

Return Values:

ERROR_SUCCESS if the information is successfully retrieved, else Win32error.

Implementation Notes:

During the marshaling of parameters to a remote device, pszMachine ismarshaled into the szTargetMachine field of the buffer.

This function needs to carefully check to see if a process actuallyexists. If the entry for a particular process is present in the<GUID>.ini file but not present in the process table, then the processno longer exists. There is a problem, however, because there may beentries in the process table for processes that have exited. Thishappens only if a WTT-based process is killed with a forced kill signal.Even doing an OpenProcess( ) on the process identifier (PID) is not afoolproof check as the PID could have been recycled. The solution is touse the Phandle pointer in the process table (on the local machine wherethe process was instantiated) to wait on the Process Handle with atimeout of zero. If the process is gone, then Phandle is signaledimmediately.

When returning the list of process information, allocate space for onemore than the total number of entries returned. The last entry is a“NULL”: NIL for GUIDs and ZERO for DWORDS.

14 WTTFreeProcessListInfo

Release the memory allocated during a WTTGetProcessListInfo functioncall. DWORD WTTFreeProcessListInfo ( INPWTTPROCLISTINFO  *ppWTTProcessListInfo );Parameter:ppWTTProcessListInfo

The array for which memory is to be released.

Return Values:

ERROR_SUCCESS if the allocated memory is successfully released, elseWin32 error.

15 WTTTailLog

Retrieve a copy of output as it is added to a log file. The effect isthat of a distributed “tail -f” command. A callback allows this functionto return asynchronously. DWORD WTTTailLog (   WTTHANDLE pWTTProcInfo,  WTTP_LOG_INFO *pWTTLogInfo,   DWORD dwBytes,   WTTPROC_CALLBACKCALLBACKFUNCTION );Parameters:

pWTTProcInfo

Information about the process of interest to be passed over to theremote device.

pWTTLogInfo

This structure contains the log information. It includes the UNC path ofthe log file. If this pointer is NULL, then the first log file is used,as specified in the <GUID>.ini file.

dwBytes

The number of bytes to be retrieved. If this is set to the valueWTTPROCESS_FULL_LOGSIZE, then entire log files are retrieved.

CALLBACKFUNCTION

Register a callback function with the spsrv service to retrieve data(the tail of the log file) asynchronously.

Return Values:

ERROR_SUCCESS if the log file stream is successfully initialized, elseWin32 error.

16 WTTCancelTailLog Cancel the effect of a previous call to WTTTailLog.DWORD WTTCancelTailLog (   WTTHANDLE pWTTProcInfo,   WTTP_LOG_INFO*pWTTLogInfo );Parameters:

pWTTProcInfo

Information about the process of interest to be passed over to theremote device.

pWTTLogInfo

This structure contains the log information. It includes the UNC path ofthe log file. If this pointer is NULL, then cancel all tail logs for theprocess identified by the pWTTProcInfo parameter.

Return Values:

ERROR_SUCCESS if the cancellation is successful, else Win32 error.

17 WTTOpenProcess

Get a WTT process handle. DWORD WTTOpenProcess (   IN WTTPROCLISTINFO*pWTTProcessInfo,   OUT WTTHANDLE *pWTTProcInfo );Parameters:

pWTTProcessInfo

A pointer to the element in the array retrieved by WTTGetProcessListInfothat concerns the process of interest.

pWTTProcInfo

A returned pointer to a handle to the process of interest.

Return Values:

ERROR_SUCCESS if the handle is successfully retrieved, else Win32 error.

Implementation Notes:

The handle has information like the GUID of the process, the name of thedevice on which the process runs, etc. Once the handle is received, itis more efficient to store its information in a local process table andto then call WTTCloseHandle to release the memory.

18 WTTCloseHandle

Close a WTT process handle. This releases the memory allocated by theWTTOpenProcess call. The local process table entry created for theprocess is marked as invalid.

DWORD WTTCloseHandle(WTTHANDLE *pWTTProcInfo);

Parameter:

pWTTProcInfo

A pointer to a handle to the process of interest.

Return Values:

ERROR_SUCCESS if the handle is successfully closed, else Win32 error.

19 WTTConsoleOutput

Provide console output for a process. A callback allows this function toreturn asynchronously. DWORD WTTConsoleOutput (   WTTHANDLEpWTTProcInfo,   WTTPROC_CALLBACK CALLBACKFUNCTION );Parameters:

pWTTProcInfo

Process information stored in a WTTHANDLE structure.

CALLBACKFUNCTION

Register a callback function with the spsrv service to retrieve dataasynchronously.

Return Values:

ERROR_SUCCESS if the console output stream is successfully initialized,else Win32 error.

20 WTTCancelConsoleOutput

Cancel the console output associated with a particular process.

DWORD WTTCancelConsoleOutput(WTTHANDLE pWTTProcInfo);

Parameter:

pWTTProcInfo

Process information stored in a WTTHANDLE structure.

Return Values:

ERROR_SUCCESS if the cancellation is successful, else Win32 error.

21 WTTSetLogFile

Add a log file to the list of log files to which a process logs. DWORDWTTSetLogFile (   WTTHANDLE pProcessInfo,   LPCWSTR pszLogFile );Parameters:

pProcessInfo

Process information stored in a WTTHANDLE structure.

pszLogFile

The name of the log file to add to the list.

Return Values:

ERROR_SUCCESS if the log file is successfully added to the list, elseWin32 error.

22 WTTPROC_CALLBACK

The functions WTTTailLog and WTTConsoleOutput use callback functions toallow them to return asynchronously. The structure of the callbackfunction is as follows: typedef DWORD (*WTTPROC_CALLBACK) (   SOCKEThSocket,   LPVOID pData,   DWORD dwBytes );23 Note on UUIDs

UUIDs (also called GUIDs) provide unique designations of objects such asprocesses, interfaces, manager entry-point vectors, and client objects.In practice, these identifiers need only be unique within the context oftheir use, that is, within the set of communicating computing devices.Because techniques already exist for making the identifiers trulyunique, those techniques are used here. typedef struct _GUID {  unsigned long Data1;   unsigned short Data2;   unsigned short Data3;  unsigned char Data4[8]; } GUID; typedef GUID UUID;Members:

-   -   Data1

The first eight hexadecimal digits of the UUID.

-   -   Data2

The first group of four hexadecimal digits of the UUID.

-   -   Data3

The second group of four hexadecimal digits of the UUID.

-   -   Data4

An array of eight elements. The first two elements of the array containthe third group of four hexadecimal digits of the UUID. The remainingsix elements contain the final twelve hexadecimal digits of the UUID.

Remarks:

For implementations based on Microsoft's “WINDOWS” operating systems,the following standard Win32 functions are used to create, compare, andmanipulate UUIDs. Other implementation platforms provide similarfunctions. signed int RPC_ENTRY UuidCompare (   sixUUID *Uuid1,  sixUUID *Uuid2,   RPC_STATUS *Status ); RPC_STATUS RPC_ENTRYUuidCreate(UUID *Uuid); RPC_ENTRY UuidCreateNil(UUID *Nil_Uuid);RPC_STATUS RPC_ENTRY UuidFromString (   unsigned char *StringUuid,  UUID *Uuid ); RPC_STATUS RPC_ENTRY UuidToString (   UUID *Uuid,  unsigned char **StringUuid );24 Note on Non-WTT-Based Processes

A suitable infrastructure is provided for tagging and monitoringnon-WTT-based processes. Every non-WTT-based process created by theWTTCreateProcess function is given a WTT-created GUID for tagging. TheGUID is stored in the WTT-based process handle for future trackingpurposes.

A Global Event handle is present for every non-WTT-based process. Thenaming structure of this handle is “Event\<GUID>” and it is present onthe device on which the process is created. When a non-WTT-based processis created, it has the option of waiting on this event handle andperforming a clean shutdown if requested.

25 Note on Locking

Central to the implementation of this API is the process table. Theprocess table has row-level exclusive locks and a global process tablelock that over-rides the row-level locks.

There are at least six points in time when locking comes into play:

-   -   (a) When the parent process looks for an empty slot in the        process table for the new child process;    -   (b) When the parent process reserves a slot in the process table        by writing in the GUID of the child process, the GUID of the        parent process, a Group GUID (if any), the time the child        process was created, the Heartbeat Time, the Source Device, the        Target Device, and the Process Type (WTT-based or non-WTT-based)        (see FIG. 4 and accompanying text for a description of these        fields);    -   (c) When the child process soon after creation writes in its        process identifier and the heartbeat time;    -   (d) When a process periodically updates the Heartbeat Time;    -   (e) When multiple processes are querying either at the row level        or at the process table level; and    -   (f) When a WTT-based process is created outside the scope of        this API. It looks for a slot in the process table and then        gives itself a GUID for identification.

Considering all these, a global lock (mutex) is needed whenever a writeaffects the entire process table, as in cases (a), (b), and (f) above. Arow-level exclusive lock is needed (after acquiring the global processtable) when updating process-specific information, as in cases (c), (d),and (e) above.

Specific Considerations when Communicating with Remote Processes

While the invention is useful when all processes run on the samecomputing device, it is also designed for the case when some processesrun remotely. This section discusses specific considerations that comeinto play when the API supports remote processes.

PWTTPROCESSINFO contains a field called szDestMachine that holds thevalue of the target device on which the process runs. If the value isNULL, then the call is local. If not, the command and its parameters aresent to the target device, and the results are piped back to theoriginating device. All calls are synchronous in nature. So, if thetarget device crashes during the period of passing the command, anappropriate error is returned.

The need to pass by value argues for using Remote Procedure Calls (RPC)as a message-passing paradigm. On the other hand, if all inputparameters to a call are based on parameters passed only by value, theninterfaces (function tables) for the call can be set up and the spsrvservice used to handle the commands on the remote device. Anotherconsideration is that if 32-bit-based machines communicate with IA64cluster machines, then RPC is very useful as it takes care ofarchitectural differences. RPC interfaces are flexible in terms ofmarshaling both pointer-based and value-based parameters.

Every time a new API call is made, a new GUID may be generated on thedevice that initiated the call. This GUID is used to “track” the call.The GUID is sent with the call to the target device. The target devicekeeps track of the GUID. If the target device crashes, then the targetdevice, after re-booting, “calls back” its parent device with theknowledge of the GUID of the last call and the name or IP address of theparent device.

For every process created on a particular device, a <GUID>.ini file iscreated in the %windir%\WTTbin\GUID directory. (For non-“WINDOWS”implementations, a similar directory is used.) This directory storesinformation about the process, its threads, and its stack comments. Thefiles store information more persistently than can memory and preventhaving to use memory for ever-changing, bulky data. A process is free toupdate the information in its file whenever the thread comments areupdated. If a query about the state of a process is made and if theprocess no longer has an entry in the process table, but a <GUID>.inifile exists, then the status of the process is updated toERROR_SERVICE_NOT_ACTIVE. Due to the presence of multiple threadspossibly operating simultaneously on this file, synchronization isimportant. A cleanup routine removes .ini files three or more days old.This is the structure of a <GUID>.ini file:

-   [GLOBAL]-   GGUID=nnn-   PID=nnn-   Status=WTT_PROCESS_RUNNING // Or some other status.-   [LogFiles]-   <Log1.log>-   <Log2.log>-   [<ThreadId1>]-   Comment1-   Comment2-   [<ThreadId2>]-   Comment1-   Comment2

For marshaling parameters for a function call, the spsrv service has afunction table that is used to form the receive and send stubs for thespsrv service running on the remote device. To form the stub forreceiving data, the buffer is as generic and as flexible as possible. Itidentifies the function, determines the number of parameters, and sets afixed order of parameters depending on the function. The followingstructure is used. It is marshaled into a byte buffer, sent out thesocket, and un-marshaled on the other end. When the call completes, thesame procedure gets the returned value of the call. // This is the indexinto the function dispatch table on the remote device. DWORDdwTestAPINum; // This usually corresponds to nCount. DWORDdwNumHWTTProcesses; // Offset into the non-variable-length buffers.DWORD dwHWTTProcOffset[MAX_PROCS]; // The number of processes present inthe WTTPROCESSMARSHALPARAM // structure (see below). DWORDdwNumMPProcesses; // Offset into the non-variable-length buffers. DWORDdwNumMPOffset[MAX_PROCS]; // The total number of bytes taken up by thebuffer. DWORD dwBytesForBuffer; DWORD dwNumWTTPLogInfo; // Offset intothe non-variable-length buffers. DWORD dwNumWTTPLogOffset[MAX_PROCS];DWORD dwNumWTTProcListElem; // Offset into the non-variable-lengthbuffers. DWORD dwNumWTTProcListOffset[MAX_PROCS]; DWORD dwWaitTimeout;DWORD dwFlags; DWORD dwWaitAll; DWORD dwBytes; // Now for storage forthe variable-length data fields. (dwNumHWTTProcesses *sizeof(_M_HWTTPROCESS)) (dwNumMPProcesses *sizeof(WTTPROCESSMARSHALPARAM)) (dwNumWTTPLogInfo *sizeof(WTTP_LOG_INFO)) (dwNumWTTProcListElem * sizeof(WTTPROCLISTINFO))

The WTTPROCESSMARSHALPARAM structure is based on WTTPROCESSPARAM buteach instance of a TCHAR * field is replaced by a DWORD dwLen<sss> and aCHAR *szStr<sss> containing a string and a NULL character. Thevariable-length data are moved to the end of the buffer so as not toaffect the offsets of the non-variable-length fields. The dwLen<sss>length information is stored with the help of the offsets. Each GUID isconverted to a string, marshaled, and then re-converted into a GUID onthe target device. WTTPROCESSMARSHALPARAM is as follows: typedef struct{   DWORD dwFlags; // Flags; currently a reserved field. Input.   DWORDdwCreateProcessFlags; // Flags used in CreateProcess. Input.   DWORDdwProcessType; // Is this a WTT-based process? Input.   DWORDdwOffSets[25]; // Offsets to the variable-length strings.   Void *pBuf;  . . . } WTTPROCESSMARSHALPARAM, *PWTTPROCESSMARSHALPARAM;The variable-length strings in WTTPROCESSMARSHALPARAM includeszUserName, szPasswd, stCommandLine, stDebugger, stClusterName,stLogFile, szGuid, szGroupGuid, szParentGuid, szSourceMachine, andszTargetMachine.

The output buffer for most calls contains the following information:information in HWTTPROCESS, marshaled as _M_HWTTPROCESS;dwSummaryStatus; and dwSummaryIndex. Variable-length data are put at theend of the buffer. For WTTGetProcessListInfo, a list is formed ofentries containing information about the processes of interest. Theinformation carried back is as follows: a list of threads presentincluding their thread identifiers; a list of comments on a per-threadbasis; and a list of variations completed by the process. The datastructures useful for marshaling this data are as follows:Struct_WTTP_THREAD_INFO {  DWORD dwThreadId;  // Offset into thecomments strings for a thread.  DWORDdwCommentOffset[MAX_COMMENTS_PER_THREAD]; } Struct_WTTP_VARIATION_INFO { // Offset into the variable-length name strings.  DWORDdwVarnNameOffset[MAX_VARNS]; } Struct_WTTP_LOG_INFO {  // Offset intothe log strings.  DWORD dwLogOffset[MAX_LOGS_PER_PROC]; }

The structure of the marshaling buffer is as follows (no pointers arepassed): // The size of this entire buffer in bytes. DWORD dwBuffSize;DWORD _dwThreadCount; // All fixed-length data for threads (i.e., thethread identifier and the offsets for the // comments) go here while theactual comments are in the variable-length section.Struct_WTTP_THREAD_INFO *pThreadInfo; DWORD _dwVariationCount;Struct_WTTP_VARIATION_INFO *pVarnInfo; DWORD _dwLogCount;Struct_WTTP_LOG_INFO *pLogInfo; (The variable-length data go here.)To be exported are the following 2 variables:

-   -   PDWORD pdwThreadCount;    -   PWTTPROCESS_THREAD_INFO *pThreadInfo;

WTTGetProcessListInfo retrieves information about a set of processes.Its return buffer contains the following information: // The size ofthis entire buffer in bytes. DWORD  dwBuffSize; // The number ofprocesses whose information is returned in this buffer. DWORD  dwProcs;DWORD  dwProcInfoOffset[WTT_MAX_PROCS]; DWORD  dwProcessId; DWORD dwGuidOffSet; DWORD  dwSrcMcOffset; DWORD  dwDestMcOffset; DWORD _dwProcListCount; // The time of the last recorded heartbeat is splitinto two parts. DWORD  LastHBTimeHighDword; DWORD  LastHBTimeLowDword;DWORD  dwHeartBeat;

In view of the many possible embodiments to which the principles of thisinvention may be applied, it should be recognized that the embodimentsdescribed herein with respect to the drawing figures are meant to beillustrative only and should not be taken as limiting the scope ofinvention. Therefore, the invention as described herein contemplates allsuch embodiments as may come within the scope of the following claimsand equivalents thereof.

1. A method for waiting for multiple processes to achieve a status, themethod comprising: issuing a wait for multiple processes call with inputparameters comprising a list of processes for which to wait, the statusto achieve, and a timeout period; receiving the wait for multipleprocesses call, parsing the call to retrieve the input parameters, andperiodically checking a heartbeat of processes in the list of processesuntil all processes reach the status or reach a default status or untilthe timeout period is passed; and issuing an acknowledgement of the waitfor multiple processes call with acknowledgement parameters comprisingthe status of the processes.
 2. A computer-readable medium havinginstructions for performing the method of claim
 1. 3. A method forwaiting for one of multiple processes to achieve a status, the methodcomprising: issuing a wait for multiple processes call with inputparameters comprising a list of processes for which to wait, the statusto achieve, and a timeout period; receiving the wait for multipleprocesses call, parsing the call to retrieve the input parameters, andperiodically checking a heartbeat of processes in the list of processesuntil any one of the processes reaches the status or until all of theprocesses reach a default status or until the timeout period is passed;and issuing an acknowledgement of the wait for multiple processes callwith acknowledgement parameters comprising the status of the processes.4. A computer-readable medium having instructions for performing themethod of claim 3.